<!DOCTYPE html>
<html>
  <head>
    <meta charset='utf-8'>
    <meta content='width=device-width, initial-scale=1.0' name='viewport'>
    <meta content='' name='description'>
    <meta content='Nils Nordman' name='author'>
    <link href='/images/howl.png' rel='shortcut icon'>
    <title>Howl :: Spec - howl.ui.ListWidget</title>
    <link href="/stylesheets/bootstrap.min.css" media="screen" rel="stylesheet" type="text/css" />
    <link href="/stylesheets/syntax.css" media="screen" rel="stylesheet" type="text/css" />
    <link href="/stylesheets/howl.css" media="screen" rel="stylesheet" type="text/css" />
    <script src="https://code.jquery.com/jquery-1.12.3.min.js" type="text/javascript"></script>
    <script src="/javascripts/bootstrap.min.js" type="text/javascript"></script>
    
    <link href='//fonts.googleapis.com/css?family=Josefin+Slab' rel='stylesheet' type='text/css'>
    <link href='//fonts.googleapis.com/css?family=Open+Sans+Condensed:700' rel='stylesheet' type='text/css'>
  </head>
  <body class='doc doc_spec doc_spec_ui doc_spec_ui_list_widget_spec'>
    <div class='container'>
      <div class='masthead'>
        <ul class='nav nav-pills'>
          <li>
            <a href='/'>
              <span class='glyphicon glyphicon-home'></span>
              Home
            </a>
          </li>
          <li>
            <a href='/doc/'>
              <span class='glyphicon glyphicon-book'></span>
              Documentation
            </a>
          </li>
          <li>
            <a href='/blog/'>
              <span class='glyphicon glyphicon-bullhorn'></span>
              Blog
            </a>
          </li>
          <li>
            <a href='/contact.html'>
              <span class='glyphicon glyphicon-inbox'></span>
              Contact
            </a>
          </li>
        </ul>
      </div>
      <ol class="breadcrumb"><li><a href="/">Home</a></li><li><a href='../../'>Howl Documentation (master branch)</a></li><li>Spec</li><li>Ui</li><li>Spec - howl.ui.ListWidget</li></ol>
      <div class="spec-group spec-group-1">&#x000A;&#x000A;<h1 id="howl.ui.listwidget">howl.ui.ListWidget</h1>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="kd">local</span><span class="w"> </span><span class="n">list</span><span class="p">,</span><span class="w"> </span><span class="n">buf</span><span class="w">&#x000A;&#x000A;</span><span class="n">before_each</span><span class="w"> </span><span class="o">-&gt;</span><span class="w">&#x000A;  </span><span class="n">list</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nc">ListWidget</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p">{}</span><span class="w">&#x000A;  </span><span class="n">list</span><span class="p">.</span><span class="n">max_rows_visible</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">100</span><span class="w">&#x000A;  </span><span class="n">list</span><span class="o">\</span><span class="n">show</span><span class="o">!</span><span class="w">&#x000A;  </span><span class="n">buf</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">list</span><span class="p">.</span><span class="n">text_widget</span><span class="p">.</span><span class="n">buffer</span></pre>&#x000A;&#x000A;<h4 id="shows-empty-list-until-update()-is-called">shows empty list until update() is called</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nc">ListWidget</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p">{</span><span class="s1">'one'</span><span class="p">,</span><span class="w"> </span><span class="s1">'two'</span><span class="p">,</span><span class="w"> </span><span class="s1">'three'</span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">show</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="s1">'(no items)'</span><span class="p">,</span><span class="w"> </span><span class="n">list</span><span class="p">.</span><span class="n">text_widget</span><span class="p">.</span><span class="n">buffer</span><span class="p">.</span><span class="n">text</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">not_equal</span><span class="w"> </span><span class="s1">'(no items)'</span><span class="p">,</span><span class="w"> </span><span class="n">list</span><span class="p">.</span><span class="n">text_widget</span><span class="p">.</span><span class="n">buffer</span><span class="p">.</span><span class="n">text</span></pre>&#x000A;&#x000A;<h4 id="shows-single-column-items,-each-on-one-line">shows single column items, each on one line</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">matcher</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p">{</span><span class="s1">'one'</span><span class="p">,</span><span class="w"> </span><span class="s1">'two'</span><span class="p">,</span><span class="w"> </span><span class="s1">'three'</span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="s1">'one  \ntwo  \nthree\n'</span><span class="p">,</span><span class="w"> </span><span class="n">buf</span><span class="p">.</span><span class="n">text</span></pre>&#x000A;&#x000A;<h4 id="allows-items-to-be-chunks">allows items to be Chunks</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">source_buf</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nc">Buffer</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">source_buf</span><span class="p">.</span><span class="n">text</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'source'</span><span class="w">&#x000A;</span><span class="n">chunk</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">source_buf</span><span class="o">\</span><span class="n">chunk</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">6</span><span class="w">&#x000A;</span><span class="n">list</span><span class="p">.</span><span class="n">matcher</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">chunk</span><span class="w"> </span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="s1">'source\n'</span><span class="p">,</span><span class="w"> </span><span class="n">buf</span><span class="p">.</span><span class="n">text</span></pre>&#x000A;&#x000A;<h4 id="shows-multi-column-items-each-on-one-line,-in-separate-columns">shows multi column items each on one line, in separate columns</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">matcher</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p">{</span><span class="w">&#x000A;  </span><span class="p">{</span><span class="s1">'first'</span><span class="p">,</span><span class="w"> </span><span class="s1">'item one'</span><span class="p">},</span><span class="w">&#x000A;  </span><span class="p">{</span><span class="s1">'second'</span><span class="p">,</span><span class="w"> </span><span class="s1">'item two'</span><span class="p">}</span><span class="w">&#x000A;</span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="p">.</span><span class="n">columns</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="p">{},</span><span class="w"> </span><span class="p">{}</span><span class="w"> </span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="sh">[[&#x000A;first  item one&#x000A;second item two&#x000A;]]</span><span class="p">,</span><span class="w"> </span><span class="n">buf</span><span class="p">.</span><span class="n">text</span></pre>&#x000A;&#x000A;<h4 id="shows-&quot;(no-items)&quot;-for-an-empty-list">shows &quot;(no items)&quot; for an empty list</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">matcher</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p">{}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="s1">'(no items)'</span><span class="p">,</span><span class="w"> </span><span class="n">buf</span><span class="p">.</span><span class="n">text</span></pre>&#x000A;&#x000A;<h4 id="shows-headers,-if-given,-above-the-items">shows headers, if given, above the items</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">matcher</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="p">{</span><span class="s1">'first'</span><span class="p">,</span><span class="w"> </span><span class="s1">'item one'</span><span class="p">}</span><span class="w"> </span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="p">.</span><span class="n">columns</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="p">{</span><span class="ss">header:</span><span class="w"> </span><span class="s1">'Header 1'</span><span class="p">},</span><span class="w"> </span><span class="p">{</span><span class="ss">header:</span><span class="w"> </span><span class="s1">'Header 2'</span><span class="p">}</span><span class="w"> </span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="sh">[[&#x000A;Header 1 Header 2&#x000A;first    item one&#x000A;]]</span><span class="p">,</span><span class="w"> </span><span class="n">buf</span><span class="p">.</span><span class="n">text</span></pre>&#x000A;&#x000A;<h4 id="all-properties-can-be-changed-after-initial-assignment">all properties can be changed after initial assignment</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">matcher</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="s1">'one'</span><span class="p">,</span><span class="w"> </span><span class="s1">'two'</span><span class="w"> </span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="n">buf</span><span class="p">.</span><span class="n">text</span><span class="p">,</span><span class="w"> </span><span class="s1">'one\ntwo\n'</span><span class="w">&#x000A;</span><span class="n">list</span><span class="p">.</span><span class="n">matcher</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="s1">'three'</span><span class="p">,</span><span class="w"> </span><span class="s1">'four'</span><span class="w"> </span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="n">buf</span><span class="p">.</span><span class="n">text</span><span class="p">,</span><span class="w"> </span><span class="s1">'three\nfour \n'</span><span class="w">&#x000A;&#x000A;</span><span class="n">list</span><span class="p">.</span><span class="n">matcher</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="s1">'three'</span><span class="p">,</span><span class="w"> </span><span class="s1">'four'</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">list</span><span class="p">.</span><span class="n">columns</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="ss">header:</span><span class="w"> </span><span class="s1">'Header 1'</span><span class="w"> </span><span class="p">},</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="ss">header:</span><span class="w"> </span><span class="s1">'Header 2'</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="sh">[[&#x000A;Header 1 Header 2&#x000A;three    four    ]]</span><span class="w"> </span><span class="o">..</span><span class="w"> </span><span class="s1">'\n'</span><span class="p">,</span><span class="w"> </span><span class="n">buf</span><span class="p">.</span><span class="n">text</span></pre>&#x000A;<div class="spec-group spec-group-2">&#x000A;&#x000A;<h3 id=""><span class="arg-list">(matching)</span></h3>&#x000A;&#x000A;<h4 id="shows-matching-items-only,-when-update(match_text)-called">shows matching items only, when update(match_text) called</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">matcher</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nc">Matcher</span><span class="w"> </span><span class="p">{</span><span class="s1">'one'</span><span class="p">,</span><span class="w"> </span><span class="s1">'twö'</span><span class="p">,</span><span class="w"> </span><span class="s1">'three'</span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="w"> </span><span class="s1">'o'</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="s1">'one\n'</span><span class="p">,</span><span class="w"> </span><span class="n">buf</span><span class="p">.</span><span class="n">text</span></pre>&#x000A;&#x000A;<h4 id="highlights-matching-parts-of-text-with-list_highlight">highlights matching parts of text with list_highlight</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">matcher</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nc">Matcher</span><span class="w"> </span><span class="p">{</span><span class="s1">'one'</span><span class="p">,</span><span class="w"> </span><span class="s1">'twö'</span><span class="p">,</span><span class="w"> </span><span class="s1">'three'</span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="w"> </span><span class="s1">'ne'</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="s1">'one\n'</span><span class="p">,</span><span class="w"> </span><span class="n">buf</span><span class="p">.</span><span class="n">text</span><span class="w">&#x000A;&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">not_includes</span><span class="w"> </span><span class="n">highlight</span><span class="p">.</span><span class="n">at_pos</span><span class="p">(</span><span class="n">buf</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">),</span><span class="w"> </span><span class="s1">'list_highlight'</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">includes</span><span class="w"> </span><span class="n">highlight</span><span class="p">.</span><span class="n">at_pos</span><span class="p">(</span><span class="n">buf</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">),</span><span class="w"> </span><span class="s1">'list_highlight'</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">includes</span><span class="w"> </span><span class="n">highlight</span><span class="p">.</span><span class="n">at_pos</span><span class="p">(</span><span class="n">buf</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">),</span><span class="w"> </span><span class="s1">'list_highlight'</span></pre>&#x000A;&#x000A;<h4 id="handles-higlighting-of-multibyte-chars">handles higlighting of multibyte chars</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">matcher</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nc">Matcher</span><span class="w"> </span><span class="p">{</span><span class="s1">'åne'</span><span class="p">,</span><span class="w"> </span><span class="s1">'twö'</span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="w"> </span><span class="s1">'ån'</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="s1">'åne\n'</span><span class="p">,</span><span class="w"> </span><span class="n">buf</span><span class="p">.</span><span class="n">text</span><span class="w">&#x000A;&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">includes</span><span class="w"> </span><span class="n">highlight</span><span class="p">.</span><span class="n">at_pos</span><span class="p">(</span><span class="n">buf</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">),</span><span class="w"> </span><span class="s1">'list_highlight'</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">includes</span><span class="w"> </span><span class="n">highlight</span><span class="p">.</span><span class="n">at_pos</span><span class="p">(</span><span class="n">buf</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">),</span><span class="w"> </span><span class="s1">'list_highlight'</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">not_includes</span><span class="w"> </span><span class="n">highlight</span><span class="p">.</span><span class="n">at_pos</span><span class="p">(</span><span class="n">buf</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">),</span><span class="w"> </span><span class="s1">'list_highlight'</span></pre>&#x000A;</div>&#x000A;<div class="spec-group spec-group-2">&#x000A;&#x000A;<h3 id=""><span class="arg-list">(when `never_shrink:` is not provided)</span></h3>&#x000A;&#x000A;<h4 id="shrinks-the-height-while-matching">shrinks the height while matching</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">matcher</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nc">Matcher</span><span class="w"> </span><span class="p">{</span><span class="s1">'one'</span><span class="p">,</span><span class="w"> </span><span class="s1">'twö'</span><span class="p">,</span><span class="w"> </span><span class="s1">'three'</span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">height</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">list</span><span class="p">.</span><span class="n">height</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">not_nil</span><span class="w"> </span><span class="n">height</span><span class="w">&#x000A;&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="w"> </span><span class="s1">'o'</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="n">height</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="n">list</span><span class="p">.</span><span class="n">height</span></pre>&#x000A;</div>&#x000A;<div class="spec-group spec-group-2">&#x000A;&#x000A;<h3 id=""><span class="arg-list">(when `never_shrink: true` is provided)</span></h3>&#x000A;&#x000A;<h4 id="does-not-shrink-the-height-while-matching">does not shrink the height while matching</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nc">ListWidget</span><span class="w"> </span><span class="nc">Matcher</span><span class="p">({</span><span class="s1">'one'</span><span class="p">,</span><span class="w"> </span><span class="s1">'twö'</span><span class="p">,</span><span class="w"> </span><span class="s1">'three'</span><span class="p">}),</span><span class="w">&#x000A;  </span><span class="ss">never_shrink:</span><span class="w"> </span><span class="kc">true</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">show</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">height</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">list</span><span class="p">.</span><span class="n">height</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">not_nil</span><span class="w"> </span><span class="n">height</span><span class="w">&#x000A;&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="w"> </span><span class="s1">'o'</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="n">height</span><span class="p">,</span><span class="w"> </span><span class="n">list</span><span class="p">.</span><span class="n">height</span></pre>&#x000A;</div>&#x000A;<div class="spec-group spec-group-2">&#x000A;&#x000A;<h3 id=""><span class="arg-list">(when .max_visible_rows is set)</span></h3>&#x000A;&#x000A;<h4 id="shows-only-up-to-max_rows_visible-rows">shows only up to max_rows_visible rows</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">matcher</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p">{</span><span class="s1">'one'</span><span class="p">,</span><span class="w"> </span><span class="s1">'two'</span><span class="p">,</span><span class="w"> </span><span class="s1">'three'</span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="p">.</span><span class="n">max_visible_rows</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">2</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="n">list</span><span class="p">.</span><span class="n">visible_rows</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">match</span><span class="w"> </span><span class="n">buf</span><span class="p">.</span><span class="n">text</span><span class="p">,</span><span class="w"> </span><span class="s1">'one'</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">is_not</span><span class="p">.</span><span class="n">match</span><span class="w"> </span><span class="n">buf</span><span class="p">.</span><span class="n">text</span><span class="p">,</span><span class="w"> </span><span class="s1">'two'</span><span class="w">&#x000A;&#x000A;</span><span class="n">list</span><span class="p">.</span><span class="n">max_visible_rows</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nb">math.huge</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="s1">'one  \ntwo  \nthree\n'</span><span class="p">,</span><span class="w"> </span><span class="n">buf</span><span class="p">.</span><span class="n">text</span></pre>&#x000A;&#x000A;<h4 id="errors-if-height-is-insufficient-to-show-at-least-one-item">errors if height is insufficient to show at least one item</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">matcher</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p">{</span><span class="s1">'one'</span><span class="p">,</span><span class="w"> </span><span class="s1">'two'</span><span class="w"> </span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="p">.</span><span class="n">max_visible_rows</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">raises</span><span class="w"> </span><span class="s1">'insufficient height'</span><span class="p">,</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span></pre>&#x000A;&#x000A;<h4 id="it-takes-headers-into-account-when-set">it takes headers into account when set</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">matcher</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p">{</span><span class="s1">'one'</span><span class="p">,</span><span class="w"> </span><span class="s1">'two'</span><span class="p">,</span><span class="w"> </span><span class="s1">'three'</span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="p">.</span><span class="n">columns</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="p">{</span><span class="ss">header:</span><span class="s1">'Takes up one line'</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="p">.</span><span class="n">max_visible_rows</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">3</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">match</span><span class="w"> </span><span class="n">buf</span><span class="p">.</span><span class="n">text</span><span class="p">,</span><span class="w"> </span><span class="s1">'one'</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">is_not</span><span class="p">.</span><span class="n">match</span><span class="w"> </span><span class="n">buf</span><span class="p">.</span><span class="n">text</span><span class="p">,</span><span class="w"> </span><span class="s1">'two'</span></pre>&#x000A;&#x000A;<h4 id="displays-info-about-the-currently-shown-items">displays info about the currently shown items</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">matcher</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p">{</span><span class="s1">'one'</span><span class="p">,</span><span class="w"> </span><span class="s1">'two'</span><span class="p">,</span><span class="w"> </span><span class="s1">'three'</span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="p">.</span><span class="n">max_visible_rows</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">2</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">match</span><span class="w"> </span><span class="n">buf</span><span class="p">.</span><span class="n">text</span><span class="p">,</span><span class="w"> </span><span class="s1">'showing 1 to 1 out of 3'</span></pre>&#x000A;</div>&#x000A;<div class="spec-group spec-group-2">&#x000A;&#x000A;<h3 id=""><span class="arg-list">(when .min_visible_rows is set)</span></h3>&#x000A;&#x000A;<h4 id="is-ignored-when-the-list-is-bigger-than-the-value">is ignored when the list is bigger than the value</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">matcher</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p">{</span><span class="s1">'one'</span><span class="p">,</span><span class="w"> </span><span class="s1">'two'</span><span class="p">,</span><span class="w"> </span><span class="s1">'three'</span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="p">.</span><span class="n">min_visible_rows</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equals</span><span class="w"> </span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="n">list</span><span class="p">.</span><span class="n">visible_rows</span></pre>&#x000A;&#x000A;<h4 id="adds-lines-to-ensure-the-given-value">adds lines to ensure the given value</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">matcher</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p">{</span><span class="s1">'one'</span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="p">.</span><span class="n">min_visible_rows</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">3</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equals</span><span class="w"> </span><span class="s1">'one\n~\n~\n'</span><span class="p">,</span><span class="w"> </span><span class="n">buf</span><span class="p">.</span><span class="n">text</span></pre>&#x000A;&#x000A;<h4 id="sets-.filler_text-for-each-filler-line-if-specified">sets .filler_text for each filler line if specified</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">matcher</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p">{</span><span class="s1">'one'</span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="p">.</span><span class="n">opts</span><span class="p">.</span><span class="n">filler_text</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'##'</span><span class="w">&#x000A;</span><span class="n">list</span><span class="p">.</span><span class="n">min_visible_rows</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">2</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equals</span><span class="w"> </span><span class="s1">'one\n##\n'</span><span class="p">,</span><span class="w"> </span><span class="n">buf</span><span class="p">.</span><span class="n">text</span></pre>&#x000A;</div>&#x000A;<div class="spec-group spec-group-2">&#x000A;&#x000A;<h2 id=".height">.height</h2>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">get_row_height</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">-&gt;</span><span class="w">&#x000A;  </span><span class="n">list</span><span class="p">.</span><span class="n">text_widget</span><span class="p">.</span><span class="n">view</span><span class="o">\</span><span class="n">text_dimensions</span><span class="p">(</span><span class="s1">'M'</span><span class="p">).</span><span class="n">height</span></pre>&#x000A;&#x000A;<h4 id="is-set-to-the-number-of-pixels-used-for-displaying-the-list">is set to the number of pixels used for displaying the list</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">matcher</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p">{</span><span class="s1">'one'</span><span class="p">,</span><span class="w"> </span><span class="s1">'two'</span><span class="p">,</span><span class="w"> </span><span class="s1">'three'</span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="mi">3</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">get_row_height</span><span class="p">(</span><span class="n">list</span><span class="p">),</span><span class="w"> </span><span class="n">list</span><span class="p">.</span><span class="n">height</span></pre>&#x000A;&#x000A;<h4 id="includes-headers">includes headers</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">matcher</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p">{</span><span class="s1">'one'</span><span class="p">,</span><span class="w"> </span><span class="s1">'two'</span><span class="p">,</span><span class="w"> </span><span class="s1">'three'</span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="p">.</span><span class="n">columns</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="ss">header:</span><span class="w"> </span><span class="s1">'Header 1'</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="mi">4</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">get_row_height</span><span class="p">(</span><span class="n">list</span><span class="p">),</span><span class="w"> </span><span class="n">list</span><span class="p">.</span><span class="n">height</span></pre>&#x000A;</div>&#x000A;<div class="spec-group spec-group-2">&#x000A;&#x000A;<h3 id=""><span class="arg-list">(when items are not strings)</span></h3>&#x000A;&#x000A;<h4 id="automatically-converts-items-to-strings-using-tostring-before-displaying">automatically converts items to strings using tostring before displaying</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">matcher</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="w"> </span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="s1">'1\n2\n'</span><span class="p">,</span><span class="w"> </span><span class="n">buf</span><span class="p">.</span><span class="n">text</span></pre>&#x000A;&#x000A;<h4 id="the-selection-is-still-the-raw-item">the selection is still the raw item</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">matcher</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="mi">57</span><span class="p">,</span><span class="w"> </span><span class="mi">59</span><span class="w"> </span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="n">list</span><span class="p">.</span><span class="n">selection</span><span class="p">,</span><span class="w"> </span><span class="mi">57</span></pre>&#x000A;</div>&#x000A;<div class="spec-group spec-group-2">&#x000A;&#x000A;<h2 id="styling">styling</h2>&#x000A;&#x000A;<h4 id="headers-are-styled-using-the-list_header-style">headers are styled using the list_header style</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">matcher</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="s1">'one'</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="p">.</span><span class="n">columns</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="ss">header:</span><span class="w"> </span><span class="s1">'Header 1'</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">header_style</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">style</span><span class="p">.</span><span class="n">at_pos</span><span class="p">(</span><span class="n">buf</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">)</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="s1">'list_header'</span><span class="p">,</span><span class="w"> </span><span class="n">header_style</span></pre>&#x000A;&#x000A;<h4 id="columns-are-styled-using-the-styles-specified-in-.columns[i].style">columns are styled using the styles specified in .columns[i].style</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">matcher</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="s1">'first'</span><span class="p">,</span><span class="w"> </span><span class="s1">'second'</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="p">.</span><span class="n">columns</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="ss">style:</span><span class="w"> </span><span class="s1">'keyword'</span><span class="p">},</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="ss">style:</span><span class="w"> </span><span class="s1">'identifier'</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="s1">'keyword'</span><span class="p">,</span><span class="w"> </span><span class="n">style</span><span class="p">.</span><span class="n">at_pos</span><span class="p">(</span><span class="n">buf</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">)</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="s1">'identifier'</span><span class="p">,</span><span class="w"> </span><span class="n">style</span><span class="p">.</span><span class="n">at_pos</span><span class="p">(</span><span class="n">buf</span><span class="p">,</span><span class="w"> </span><span class="mi">7</span><span class="p">)</span></pre>&#x000A;</div>&#x000A;<div class="spec-group spec-group-2">&#x000A;&#x000A;<h3 id=""><span class="arg-list">(selection)</span></h3>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">before_each</span><span class="w"> </span><span class="o">-&gt;</span><span class="w">&#x000A;  </span><span class="n">list</span><span class="p">.</span><span class="n">matcher</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="s1">'one'</span><span class="p">,</span><span class="w"> </span><span class="s1">'two'</span><span class="p">,</span><span class="w"> </span><span class="s1">'three'</span><span class="w"> </span><span class="p">}</span><span class="w">&#x000A;  </span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span></pre>&#x000A;&#x000A;<h4 id="selects-the-first-item-by-default">selects the first item by default</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="s1">'one'</span><span class="p">,</span><span class="w"> </span><span class="n">list</span><span class="p">.</span><span class="n">selection</span></pre>&#x000A;&#x000A;<h4 id=".selection-is-nil-for-an-empty-list">.selection is nil for an empty list</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">matcher</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p">{}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">is_nil</span><span class="w"> </span><span class="n">list</span><span class="p">.</span><span class="n">selection</span></pre>&#x000A;&#x000A;<h4 id="highlights-the-selected-item-with-list_selection">highlights the selected item with list_selection</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">assert</span><span class="p">.</span><span class="n">same</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="s1">'list_selection'</span><span class="w"> </span><span class="p">},</span><span class="w"> </span><span class="n">highlight</span><span class="p">.</span><span class="n">at_pos</span><span class="p">(</span><span class="n">buf</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">)</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">same</span><span class="w"> </span><span class="p">{},</span><span class="w"> </span><span class="n">highlight</span><span class="p">.</span><span class="n">at_pos</span><span class="p">(</span><span class="n">buf</span><span class="p">,</span><span class="w"> </span><span class="n">buf</span><span class="p">.</span><span class="n">lines</span><span class="p">[</span><span class="mi">2</span><span class="p">].</span><span class="n">start_pos</span><span class="p">)</span></pre>&#x000A;&#x000A;<h4 id="adjusts-highlight-when-headers-present">adjusts highlight when headers present</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">columns</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="ss">header:</span><span class="w"> </span><span class="s1">'Head'</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">same</span><span class="w"> </span><span class="p">{},</span><span class="w"> </span><span class="n">highlight</span><span class="p">.</span><span class="n">at_pos</span><span class="p">(</span><span class="n">buf</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">)</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">same</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="s1">'list_selection'</span><span class="w"> </span><span class="p">},</span><span class="w"> </span><span class="n">highlight</span><span class="p">.</span><span class="n">at_pos</span><span class="p">(</span><span class="n">buf</span><span class="p">,</span><span class="w"> </span><span class="n">buf</span><span class="p">.</span><span class="n">lines</span><span class="p">[</span><span class="mi">2</span><span class="p">].</span><span class="n">start_pos</span><span class="p">)</span></pre>&#x000A;&#x000A;<h4 id="pads-lines-if-neccessary-to-achieve-a-uniform-selection-highlight">pads lines if neccessary to achieve a uniform selection highlight</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="mi">5</span><span class="p">,</span><span class="w"> </span><span class="o">#</span><span class="n">buf</span><span class="p">.</span><span class="n">lines</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="mi">5</span><span class="p">,</span><span class="w"> </span><span class="o">#</span><span class="n">buf</span><span class="p">.</span><span class="n">lines</span><span class="p">[</span><span class="mi">3</span><span class="p">]</span></pre>&#x000A;<div class="spec-group spec-group-3">&#x000A;&#x000A;<h3 id=".selection-=-&lt;item&gt;">.selection = &lt;item&gt;</h3>&#x000A;&#x000A;<h4 id="causes-&lt;item&gt;-to-be-selected">causes &lt;item&gt; to be selected</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">selection</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'two'</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="n">list</span><span class="p">.</span><span class="n">selection</span><span class="p">,</span><span class="w"> </span><span class="s1">'two'</span></pre>&#x000A;&#x000A;<h4 id="raises-an-error-if-&lt;item&gt;-can-not-be-found">raises an error if &lt;item&gt; can not be found</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">assert</span><span class="p">.</span><span class="n">raises</span><span class="w"> </span><span class="s1">'not found'</span><span class="p">,</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="n">list</span><span class="p">.</span><span class="n">selection</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'five'</span></pre>&#x000A;&#x000A;<h4 id="highlights-the-new-selection-and-clears-any-old-highlight">highlights the new selection and clears any old highlight</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">selection</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'one'</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">same</span><span class="w"> </span><span class="n">highlight</span><span class="p">.</span><span class="n">at_pos</span><span class="p">(</span><span class="n">buf</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">),</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="s1">'list_selection'</span><span class="w"> </span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="p">.</span><span class="n">selection</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'two'</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">same</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="s1">'list_selection'</span><span class="w"> </span><span class="p">},</span><span class="w"> </span><span class="n">highlight</span><span class="p">.</span><span class="n">at_pos</span><span class="p">(</span><span class="n">buf</span><span class="p">,</span><span class="w"> </span><span class="n">buf</span><span class="p">.</span><span class="n">lines</span><span class="p">[</span><span class="mi">2</span><span class="p">].</span><span class="n">start_pos</span><span class="p">)</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">same</span><span class="w"> </span><span class="p">{},</span><span class="w"> </span><span class="n">highlight</span><span class="p">.</span><span class="n">at_pos</span><span class="p">(</span><span class="n">buf</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">)</span></pre>&#x000A;&#x000A;<h4 id="scrolls-the-list-if-needed">scrolls the list if needed</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">max_visible_rows</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">2</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">list</span><span class="p">.</span><span class="n">selection</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'three'</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">match</span><span class="w"> </span><span class="n">buf</span><span class="p">.</span><span class="n">text</span><span class="p">,</span><span class="w"> </span><span class="s1">'three'</span></pre>&#x000A;</div>&#x000A;<div class="spec-group spec-group-3">&#x000A;&#x000A;<h3 id="select_next">select_next<span class="arg-list">()</span></h3>&#x000A;&#x000A;<h4 id="selects-the-next-item">selects the next item</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="o">\</span><span class="n">select_next</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="s1">'two'</span><span class="p">,</span><span class="w"> </span><span class="n">list</span><span class="p">.</span><span class="n">selection</span></pre>&#x000A;&#x000A;<h4 id="selects-the-first-item-if-at-the-end-of-the-list">selects the first item if at the end of the list</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">selection</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'three'</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">select_next</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="s1">'one'</span><span class="p">,</span><span class="w"> </span><span class="n">list</span><span class="p">.</span><span class="n">selection</span></pre>&#x000A;&#x000A;<h4 id="scrolls-to-the-item-if-neccessary">scrolls to the item if neccessary</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">max_visible_rows</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">2</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">select_next</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="s1">'two'</span><span class="p">,</span><span class="w"> </span><span class="n">list</span><span class="p">.</span><span class="n">selection</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">match</span><span class="w"> </span><span class="n">buf</span><span class="p">.</span><span class="n">text</span><span class="p">,</span><span class="w"> </span><span class="s1">'two'</span></pre>&#x000A;</div>&#x000A;<div class="spec-group spec-group-3">&#x000A;&#x000A;<h3 id="select_prev">select_prev<span class="arg-list">()</span></h3>&#x000A;&#x000A;<h4 id="selects-the-previous-item">selects the previous item</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">selection</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'three'</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">select_prev</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="s1">'two'</span><span class="p">,</span><span class="w"> </span><span class="n">list</span><span class="p">.</span><span class="n">selection</span></pre>&#x000A;&#x000A;<h4 id="selects-the-last-item-if-at-the-start-of-the-list">selects the last item if at the start of the list</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="o">\</span><span class="n">select_prev</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="n">list</span><span class="p">.</span><span class="n">selection</span><span class="p">,</span><span class="w"> </span><span class="s1">'three'</span></pre>&#x000A;&#x000A;<h4 id="scrolls-to-the-item-if-neccessary">scrolls to the item if neccessary</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">max_visible_rows</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">2</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">list</span><span class="p">.</span><span class="n">selection</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'three'</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">select_prev</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="s1">'two'</span><span class="p">,</span><span class="w"> </span><span class="n">list</span><span class="p">.</span><span class="n">selection</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">match</span><span class="w"> </span><span class="n">buf</span><span class="p">.</span><span class="n">text</span><span class="p">,</span><span class="w"> </span><span class="s1">'two'</span></pre>&#x000A;</div>&#x000A;</div>&#x000A;<div class="spec-group spec-group-2">&#x000A;&#x000A;<h2 id="next_page">next_page<span class="arg-list">()</span></h2>&#x000A;&#x000A;<h4 id="scrolls-to-the-next-page">scrolls to the next page</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">matcher</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p">{</span><span class="s1">'one'</span><span class="p">,</span><span class="w"> </span><span class="s1">'two'</span><span class="p">,</span><span class="w"> </span><span class="s1">'three'</span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="p">.</span><span class="n">max_visible_rows</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">2</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">next_page</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="n">list</span><span class="p">.</span><span class="n">offset</span></pre>&#x000A;&#x000A;<h4 id="scrolls-to-the-first-page-if-at-the-end-of-the-list">scrolls to the first page if at the end of the list</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">matcher</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p">{</span><span class="s1">'one'</span><span class="p">,</span><span class="w"> </span><span class="s1">'two'</span><span class="p">,</span><span class="w"> </span><span class="s1">'three'</span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="p">.</span><span class="n">max_visible_rows</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">2</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">list</span><span class="p">.</span><span class="n">selection</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'three'</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">next_page</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="n">list</span><span class="p">.</span><span class="n">offset</span></pre>&#x000A;</div>&#x000A;<div class="spec-group spec-group-2">&#x000A;&#x000A;<h2 id="prev_page">prev_page<span class="arg-list">()</span></h2>&#x000A;&#x000A;<h4 id="scrolls-to-the-previous-page">scrolls to the previous page</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">matcher</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p">{</span><span class="s1">'one'</span><span class="p">,</span><span class="w"> </span><span class="s1">'two'</span><span class="p">,</span><span class="w"> </span><span class="s1">'three'</span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="p">.</span><span class="n">max_visible_rows</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">2</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">list</span><span class="p">.</span><span class="n">selection</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'three'</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">prev_page</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="n">list</span><span class="p">.</span><span class="n">offset</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span></pre>&#x000A;&#x000A;<h4 id="scrolls-to-the-last-page-if-at-the-start-of-the-list">scrolls to the last page if at the start of the list</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">list</span><span class="p">.</span><span class="n">matcher</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p">{</span><span class="s1">'one'</span><span class="p">,</span><span class="w"> </span><span class="s1">'two'</span><span class="p">,</span><span class="w"> </span><span class="s1">'three'</span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">list</span><span class="p">.</span><span class="n">max_visible_rows</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">2</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">update</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">list</span><span class="o">\</span><span class="n">prev_page</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="n">list</span><span class="p">.</span><span class="n">offset</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span></pre>&#x000A;</div>&#x000A;<div class="spec-group spec-group-2">&#x000A;&#x000A;<h3 id=""><span class="arg-list">(when reverse is true)</span></h3>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="kd">local</span><span class="w"> </span><span class="n">rlist</span><span class="p">,</span><span class="w"> </span><span class="n">rbuf</span><span class="w">&#x000A;&#x000A;</span><span class="n">before_each</span><span class="w"> </span><span class="o">-&gt;</span><span class="w">&#x000A;  </span><span class="n">matcher</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="s1">'one'</span><span class="p">,</span><span class="w"> </span><span class="s1">'two'</span><span class="p">,</span><span class="w"> </span><span class="s1">'three'</span><span class="w"> </span><span class="p">}</span><span class="w">&#x000A;  </span><span class="n">rlist</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nc">ListWidget</span><span class="w"> </span><span class="n">matcher</span><span class="p">,</span><span class="w"> </span><span class="ss">reverse:</span><span class="w"> </span><span class="kc">true</span><span class="w">&#x000A;  </span><span class="n">rlist</span><span class="o">\</span><span class="n">show</span><span class="o">!</span><span class="w">&#x000A;  </span><span class="n">rbuf</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">rlist</span><span class="p">.</span><span class="n">text_widget</span><span class="p">.</span><span class="n">buffer</span><span class="w">&#x000A;  </span><span class="n">rlist</span><span class="o">\</span><span class="n">update</span><span class="o">!</span></pre>&#x000A;&#x000A;<h4 id="shows-the-items-in-reverse-order">shows the items in reverse order</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="s1">'three\ntwo  \none  \n'</span><span class="p">,</span><span class="w"> </span><span class="n">rbuf</span><span class="p">.</span><span class="n">text</span></pre>&#x000A;&#x000A;<h4 id="selects-the-last-item-by-default">selects the last item by default</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="s1">'one'</span><span class="p">,</span><span class="w"> </span><span class="n">rlist</span><span class="p">.</span><span class="n">selection</span></pre>&#x000A;</div>&#x000A;<div class="spec-group spec-group-2">&#x000A;&#x000A;<h3 id=""><span class="arg-list">(resource management)</span></h3>&#x000A;&#x000A;<h4 id="widgets-are-collected-as-they-should">widgets are collected as they should</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">w</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nc">ListWidget</span><span class="w"> </span><span class="p">(</span><span class="o">-&gt;</span><span class="p">)</span><span class="w">&#x000A;</span><span class="n">list</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nb">setmetatable</span><span class="w"> </span><span class="p">{</span><span class="n">w</span><span class="p">},</span><span class="w"> </span><span class="ss">__mode:</span><span class="w"> </span><span class="s1">'v'</span><span class="w">&#x000A;</span><span class="n">w</span><span class="o">\</span><span class="n">to_gobject</span><span class="o">!\</span><span class="n">destroy</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">w</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kc">nil</span><span class="w">&#x000A;</span><span class="nb">collectgarbage</span><span class="o">!</span><span class="w">&#x000A;</span><span class="n">assert</span><span class="p">.</span><span class="n">is_nil</span><span class="w"> </span><span class="n">list</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span></pre>&#x000A;&#x000A;<h4 id="memory-usage-is-stable">memory usage is stable</h4>&#x000A;&#x000A;<pre class="highlight moonscript"><span class="n">items</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="s1">'one'</span><span class="p">,</span><span class="w"> </span><span class="s1">'two'</span><span class="p">,</span><span class="w"> </span><span class="s1">'three'</span><span class="p">}</span><span class="w">&#x000A;</span><span class="n">assert_memory_stays_within</span><span class="w"> </span><span class="s1">'50Kb'</span><span class="p">,</span><span class="w"> </span><span class="mi">30</span><span class="p">,</span><span class="w"> </span><span class="o">-&gt;</span><span class="w">&#x000A;  </span><span class="n">w</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nc">ListWidget</span><span class="w"> </span><span class="p">(</span><span class="o">-&gt;</span><span class="w"> </span><span class="n">items</span><span class="p">)</span><span class="w">&#x000A;  </span><span class="n">w</span><span class="o">\</span><span class="n">show</span><span class="o">!</span><span class="w">&#x000A;  </span><span class="n">w</span><span class="o">\</span><span class="n">to_gobject</span><span class="o">!\</span><span class="n">destroy</span><span class="o">!</span></pre>&#x000A;</div>&#x000A;</div>
      <div class='footer text-muted'>
        <a href='/'>
          <img width="50" height="50" class="footer-logo" src="/images/howl.png" />
        </a>
        <div class='footer-follow'>
          <p>
            <a class='twitter-follow-button' data-lang='en' data-show-count='false' href='https://twitter.com/howleditor' rel='me'>
              Follow @howleditor
            </a>
          </p>
          <p>
            <a class='twitter-share-button' data-count='none' data-hashtags='howleditor' data-lang='en' data-text='The Howl Editor, a general purpose, light-weight customizable editor.' data-url='http://howl.io' href='https://twitter.com/share'>
              Tweet
            </a>
          </p>
        </div>
        <div class='footer-blurb'>
          <div>The Howl editor.</div>
          <div>
            Copyright 2012-2016
            <a class='alert-link' href='https://github.com/howl-editor/howl/contributors'>
              The Howl Developers.
            </a>
          </div>
        </div>
      </div>
    </div>
    <script>
      <!-- / GA -->
      (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
      (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
      m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
      })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
      ga('create', 'UA-45283282-1', 'howl.io');
      ga('send', 'pageview');
      <!-- / Twitter -->
      !function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];
      if(!d.getElementById(id)){js=d.createElement(s);js.id=id;
      js.src="//platform.twitter.com/widgets.js";
      fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");
    </script>
  </body>
</html>
